<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="topic1">
    <title id="jq20941">gpcheckperf</title>
    <body>
        <p>Verifies the baseline hardware performance of the specified hosts.</p>
        <section id="section2">
            <title>Synopsis</title>
            <codeblock>gpcheckperf -d &lt;test_directory> [-d &lt;test_directory> ...] 
    {-f &lt;hostfile_gpcheckperf> | - h &lt;hostname> [-h hostname ...]} 
    [-r ds] [-B &lt;block_size>] [-S &lt;file_size>] [-D] [-v|-V]

gpcheckperf -d &lt;temp_directory>
    {-f &lt;hostfile_gpchecknet> | - h &lt;hostname> [-h&lt; hostname> ...]} 
    [ -r n|N|M [--duration &lt;time>] [--netperf] ] [-D] [-v | -V]

gpcheckperf -?

gpcheckperf --version</codeblock>
        </section>
        <section id="section3">
            <title>Description</title>
            <p>The <codeph>gpcheckperf</codeph> utility starts a session on the specified hosts and
                runs the following performance tests:</p>
            <ul>
                <li id="jq141274"><b>Disk I/O Test (dd test)</b> — To test the sequential throughput
                    performance of a logical disk or file system, the utility uses the <b>dd</b>
                    command, which is a standard UNIX utility. It times how long it takes to write
                    and read a large file to and from disk and calculates your disk I/O performance
                    in megabytes (MB) per second. By default, the file size that is used for the
                    test is calculated at two times the total random access memory (RAM) on the
                    host. This ensures that the test is truly testing disk I/O and not using the
                    memory cache.</li>
                <li id="jq141275"><b>Memory Bandwidth Test (stream)</b> — To test memory bandwidth,
                    the utility uses the STREAM benchmark program to measure sustainable memory
                    bandwidth (in MB/s). This tests that your system is not limited in performance
                    by the memory bandwidth of the system in relation to the computational
                    performance of the CPU. In applications where the data set is large (as in
                    Greenplum Database), low memory bandwidth is a major performance issue. If
                    memory bandwidth is significantly lower than the theoretical bandwidth of the
                    CPU, then it can cause the CPU to spend significant amounts of time waiting for
                    data to arrive from system memory.</li>
                <li id="jq141279"><b>Network Performance Test (gpnetbench*)</b> — To test network
                    performance (and thereby the performance of the Greenplum Database
                    interconnect), the utility runs a network benchmark program that transfers a 5
                    second stream of data from the current host to each remote host included in the
                    test. The data is transferred in parallel to each remote host and the minimum,
                    maximum, average and median network transfer rates are reported in megabytes
                    (MB) per second. If the summary transfer rate is slower than expected (less than
                    100 MB/s), you can run the network test serially using the <codeph>-r n</codeph>
                    option to obtain per-host results. To run a full-matrix bandwidth test, you can
                    specify <codeph>-r M</codeph> which will cause every host to send and receive
                    data from every other host specified. This test is best used to validate if the
                    switch fabric can tolerate a full-matrix workload.</li>
            </ul>
            <p>To specify the hosts to test, use the <codeph>-f</codeph> option to specify a file
                containing a list of host names, or use the <codeph>-h</codeph> option to name
                single host names on the command-line. If running the network performance test, all
                entries in the host file must be for network interfaces within the same subnet. If
                your segment hosts have multiple network interfaces configured on different subnets,
                run the network test once for each subnet.</p>
            <p>You must also specify at least one test directory (with <codeph>-d</codeph>). The
                user who runs <codeph>gpcheckperf</codeph> must have write access to the specified
                test directories on all remote hosts. For the disk I/O test, the test directories
                should correspond to your segment data directories (primary and/or mirrors). For the
                memory bandwidth and network tests, a temporary directory is required for the test
                program files.</p>
            <p>Before using <codeph>gpcheckperf</codeph>, you must have a trusted host setup between
                the hosts involved in the performance test. You can use the utility
                    <codeph>gpssh-exkeys</codeph> to update the known host files and exchange public
                keys between hosts if you have not done so already. Note that
                    <codeph>gpcheckperf</codeph> calls to <codeph>gpssh</codeph> and
                    <codeph>gpscp</codeph>, so these Greenplum utilities must also be in your
                    <codeph>$PATH</codeph>.</p>
        </section>
        <section id="section4">
            <title>Options</title>
            <parml>
                <plentry>
                    <pt>-B <varname>block_size</varname></pt>
                    <pd>Specifies the block size (in KB or MB) to use for disk I/O test. The default
                        is 32KB, which is the same as the Greenplum Database page size. The maximum
                        block size is 1 MB.</pd>
                </plentry>
                <plentry>
                    <pt>-d <varname>test_directory</varname></pt>
                    <pd>For the disk I/O test, specifies the file system directory locations to
                        test. You must have write access to the test directory on all hosts involved
                        in the performance test. You can use the <codeph>-d</codeph> option multiple
                        times to specify multiple test directories (for example, to test disk I/O of
                        your primary and mirror data directories).</pd>
                </plentry>
                <plentry>
                    <pt>-d <varname>temp_directory</varname></pt>
                    <pd>For the network and stream tests, specifies a single directory where the
                        test program files will be copied for the duration of the test. You must
                        have write access to this directory on all hosts involved in the test.</pd>
                </plentry>
                <plentry>
                    <pt>-D (display per-host results)</pt>
                    <pd>Reports performance results for each host for the disk I/O tests. The
                        default is to report results for just the hosts with the minimum and maximum
                        performance, as well as the total and average performance of all hosts.</pd>
                </plentry>
                <plentry>
                    <pt>--duration <varname>time</varname></pt>
                    <pd>Specifies the duration of the network test in seconds (s), minutes (m),
                        hours (h), or days (d). The default is 15 seconds.</pd>
                </plentry>
                <plentry>
                    <pt>-f <varname>hostfile_gpcheckperf</varname></pt>
                    <pd>For the disk I/O and stream tests, specifies the name of a file that
                        contains one host name per host that will participate in the performance
                        test. The host name is required, and you can optionally specify an alternate
                        user name and/or SSH port number per host. The syntax of the host file is
                        one host per line as follows:</pd>
                    <pd>
                        <codeblock>[&lt;username>@]&lt;hostname>[:&lt;ssh_port>]</codeblock>
                    </pd>
                </plentry>
                <plentry>
                    <pt>-f <varname>hostfile_gpchecknet</varname></pt>
                    <pd>For the network performance test, all entries in the host file must be for
                        host addresses within the same subnet. If your segment hosts have multiple
                        network interfaces configured on different subnets, run the network test
                        once for each subnet. For example (a host file containing segment host
                        address names for interconnect subnet 1):</pd>
                    <pd>
                        <codeblock>sdw1-1
sdw2-1
sdw3-1</codeblock>
                    </pd>
                </plentry>
                <plentry>
                    <pt>-h <varname>hostname</varname></pt>
                    <pd>Specifies a single host name (or host address) that will participate in the
                        performance test. You can use the <codeph>-h</codeph> option multiple times
                        to specify multiple host names.</pd>
                </plentry>
                <plentry>
                    <pt>--netperf</pt>
                    <pd>Specifies that the <codeph>netperf</codeph> binary should be used to perform
                        the network test instead of the Greenplum network test. To use this option,
                        you must download <codeph>netperf</codeph> from <xref
                            href="https://github.com/HewlettPackard/netperf" format="html" scope="external"/> and
                        install it into <codeph>$GPHOME/bin/lib</codeph> on all Greenplum hosts
                        (master and segments).</pd>
                </plentry>
                <plentry>
                    <pt>-r ds{n|N|M}</pt>
                    <pd>Specifies which performance tests to run. The default is
                            <codeph>dsn</codeph>:<ul id="ul_jjn_vvt_mo">
                            <li id="jq141318">Disk I/O test (<codeph>d</codeph>)</li>
                            <li id="jq141319">Stream test (<codeph>s</codeph>)</li>
                            <li id="jq141320">Network performance test in sequential
                                    (<codeph>n</codeph>), parallel (<codeph>N</codeph>), or
                                full-matrix (<codeph>M</codeph>) mode. The optional
                                    <codeph>--duration</codeph> option specifies how long (in
                                seconds) to run the network test. To use the parallel
                                    (<codeph>N</codeph>) mode, you must run the test on an
                                    <varname>even</varname> number of hosts.<p>If you would rather
                                    use <codeph>netperf</codeph> (<xref
                                        href="https://github.com/HewlettPackard/netperf" format="html" scope="external"
                                    />) instead of the Greenplum network test, you can download it
                                    and install it into <codeph>$GPHOME/bin/lib</codeph> on all
                                    Greenplum hosts (master and segments). You would then specify
                                    the optional <codeph>--netperf</codeph> option to use the
                                        <codeph>netperf</codeph> binary instead of the default
                                        <codeph>gpnetbench*</codeph> utilities.</p></li>
                        </ul></pd>
                </plentry>
                <plentry>
                    <pt>-S <varname>file_size</varname></pt>
                    <pd>Specifies the total file size to be used for the disk I/O test for all
                        directories specified with <codeph>-d</codeph>. <varname>file_size</varname>
                        should equal two times total RAM on the host. If not specified, the default
                        is calculated at two times the total RAM on the host where
                            <codeph>gpcheckperf</codeph> is run. This ensures that the test is
                        truly testing disk I/O and not using the memory cache. You can specify
                        sizing in KB, MB, or GB.</pd>
                </plentry>
                <plentry>
                    <pt>-v (verbose) | -V (very verbose)</pt>
                    <pd>Verbose mode shows progress and status messages of the performance tests as
                        they are run. Very verbose mode shows all output messages generated by this
                        utility.</pd>
                </plentry>
                <plentry>
                    <pt>--version</pt>
                    <pd>Displays the version of this utility.</pd>
                </plentry>
                <plentry>
                    <pt>-? (help)</pt>
                    <pd>Displays the online help.</pd>
                </plentry>
            </parml>
        </section>
        <section id="section5">
            <title>Examples</title>
            <p>Run the disk I/O and memory bandwidth tests on all the hosts in the file
                    <varname>host_file</varname> using the test directory of
                    <varname>/data1</varname> and <varname>/data2</varname>:</p>
            <codeblock>$ gpcheckperf -f hostfile_gpcheckperf -d /data1 -d /data2 -r ds</codeblock>
            <p>Run only the disk I/O test on the hosts named <varname>sdw1</varname> and
                    <varname>sdw2 </varname>using the test directory of <varname>/data1</varname>.
                Show individual host results and run in verbose mode:</p>
            <codeblock>$ gpcheckperf -h sdw1 -h sdw2 -d /data1 -r d -D -v</codeblock>
            <p>Run the parallel network test using the test directory of <varname>/tmp,</varname>
                where <varname>hostfile_gpcheck_ic*</varname> specifies all network interface host
                address names within the same interconnect subnet:</p>
            <codeblock>$ gpcheckperf -f hostfile_gpchecknet_ic1 -r N -d /tmp
$ gpcheckperf -f hostfile_gpchecknet_ic2 -r N -d /tmp</codeblock>
            <p>Run the same test as above, but use <codeph>netperf</codeph> instead of the Greenplum
                network test (note that <codeph>netperf</codeph> must be installed in
                    <codeph>$GPHOME/bin/lib</codeph> on all Greenplum hosts):</p>
            <codeblock>$ gpcheckperf -f hostfile_gpchecknet_ic1 -r N --netperf -d /tmp
$ gpcheckperf -f hostfile_gpchecknet_ic2 -r N --netperf -d /tmp</codeblock>
        </section>
        <section id="section6">
            <title>See Also</title>
            <p><xref href="./gpssh.xml#topic1" type="topic" format="dita"/>, <xref
                    href="./gpscp.xml#topic1" type="topic" format="dita"/></p>
        </section>
    </body>
</topic>
